<!doctype html>
<html>
	<head>
		<meta charset="UTF-8">
		<title>Spark documentation</title>
		<link rel="stylesheet" href="../docs/screen.css" type="text/css" media="screen, projection">
		<link rel="stylesheet" href="../docs/print.css" type="text/css" media="print">
		<link rel="shortcut icon" href="../docs/favicon.ico" />
	</head>
	<body>
		<div class="container">
			<div class="span-24 last prepend-top">
				<header>
					<h1><a href="../index.html"><img src="spark-logo.png" alt="Spark" label="Spark"></a></h1>
					<h2>Documentation</h2>
				</header>
				<p>
The documentation is work in progress.
				</p>
				<ol>
					<li><a href="#intro">Introduction and background</a></li>
					<li><a href="#include">How to include Spark</a></li>
					<li><a href="#include">Spark markup</a></li>
					<li><a href="#javascript">Using Spark from JavaScript</a></li>
					<li><a href="#formats">Spark query result formats</a></li>
					<li><a href="#newformats">Write your own Spark query result format</a></li>
					<li><a href="#mediawiki">Spark in MediaWiki</a></li>
					<li><a href="#drupal">Spark in Drupal</a></li>
					<li><a href="#wordpress">Spark in Wordpress</a></li>
					<li><a href="#examples">Examples</a></li>
					<li><a href="#development">Spark development</a></li>
					<li><a href="#cite">How to acknowledge / cite Spark</a></li>
				</ol>
				<h2 id="intro">Introduction and background</h2>
				<p>
The web is not only growing in sheer size, but it also grows in how much it is
interconnected. Where once the Web was a set of more or less separated sites,
today sites are more and more being connected. More and more data is being
offered on the Web in a way that can be further processed, and more and more
sites and applications are using external data. More and more mashups are
created, where data from different sources is integrated and displayed with
novel visualisations.
				</p>
				<p>
<strong>Spark</strong> is a library that enables HTML authors to create mashups
more easily than ever before. Using standard Web technologies like SPARQL, RDF,
HTML5, and JavaScript, <strong>Spark</strong> can query external knowledge
sources (so called triple stores or SPARQL endpoints), and then visualise the
results.
				</p>
				<p>
With <strong>Spark</strong>, website developers can create visually appealing
mashups without having to write a single line of JavaScript, but merely using
some markup elements describing the source of the data that is to be shown, a
query to select the appropriate data, and selecting one from an expandable set
of visualisations and their parameters.
				</p>
				<h3>Further references</h3>
				<ul>
					<li><a href="http://en.wikipedia.org/wiki/Linked_Data">Linked Data</a></li
					<li><a href="http://en.wikipedia.org/wiki/RDF">RDF</a></li>
					<li><a href="http://en.wikipedia.org/wiki/SPARQL">SPARQL</a></li>
				</ul>
				<h2 id="include">How to include Spark</h2>
				<p>
<strong>Spark</strong> requires jQuery to run. In order to include jQuery, you
can either include it from the Web, e.g. from Google's Content Delivery Network
like this:
				</p>
				<p>
					<code>
&lt;script src=&quot;https://ajax.googleapis.com/ajax/libs/jquery/1.4.4/jquery.min.js&quot;&gt;&lt;/script&gt;
					</code>
				</p>
				<p>
For development, we are using jQuery Version 1.4.4, but it should work with a
reasonable range of versions.
				</p>
				<p>
Once jQuery is included, there are two ways to include <strong>Spark</strong>
into your website:
1) include it from our Website, or 2) download it and include it locally.
In order to include it from our Website, put the following statement
<em>after</em> you have included the jQuery library.
				</p>
				<p>
					<code>
&lt;script src=&quot;http://km.aifb.kit.edu/sites/spark/src/jquery.spark.js&quot;&gt;&lt;/script&gt;
					</code>
				</p>
				<p>
If you download the library yourself, upload it to your site and simply include
the <code>jquery.spark.js</code> script from wherever you have uploaded it.
				</p>
				<p>
Note that some formats may require you to include further JavaScript- or
CSS-files in order to run properly. These additional files should be listed
in the documentation of the format.
				</p>
				<p>
<strong>Spark</strong> also requires a sensibly modern browser to run. Currently, Internet Explorer
is not supported due to problems with cross-site data access. We are hoping to
resolve that soon.
				</p>
				<h2 id="markup">Spark markup</h2>
				<p>
Once included, HTML elements can be marked up for <strong>Spark</strong> to
process them. In order to do that, you need to add a
<code>class=&quot;spark&quot;</code>
to your element, e.g. like this
<code>&lt;span class=&quot;spark&quot;&gt;</code>.
Now you need to add the parameters for the call to <strong>Spark</strong>. The
order of the parameters does not matter. Each parameter must only be used once.
The following parameters are generally available:
				</p>
				<ul>
					<li>
<code>data-spark-endpoint</code>: The URL of the SPARQL endpoint to be queried.
Per default, the <a href="http://qcrumb.com">qcrumb.com</a> endpoint will be used.
					</li>
					<li>
<code>data-spark-rdf</code>: The URL of the RDF-file with the data to be
queried. This can be omitted if a SPARQL endpoint is given.
					</li>
					<li>
<code>data-spark-format</code>: The format to use for rendering the result.
Note that you can simply use your own formats, since you can enter here the
URL of the JavaScript file containing the formatter. Otherwise, the simple
formatter is assumed.
					</li>
					<li>
<code>data-spark-query</code>: The SPARQL query to be executed. Note that the
query does not require to be complete, including all namespace declarations
etc., but that you can add namespace declarations via the following parameter.
					</li>
					<li>
<code>data-spark-ns-*</code>: Namespace declaration. Instead of <code>*</code>
you write the namespace prefix, the attribute value gives the actual namespace.
Note that Spark already declares a <a href="#ns">small set of namespaces</a> for convenience.
					</li>
					<li>
<code>data-spark-param-*</code>: Further parameters as used by the given
format. These parameters are documented on the format documentation.
					</li>
				</ul>
				<p>
Further parameters may be available for a given format. These parameters are
described in the documentation of the respective format. 
				</p>
				<p>
Note that most formats will remove whatever the element used to have as a
content. Thus it might be useful to put in some content in the pure HTML
element that indicates that this element will be replaced (e.g. text like
<em>loading&hellip;</em>).
				</p>
				<h2 id="javascript">Using Spark from JavaScript</h2>
				<p>
<strong>Spark</strong> can also be used from JavaScript directly, without
having to use the additional mark-up. Spark adds a new function
<code>spark</code> to the jQuery element wrapper, which can be called with one
parameter, an options object (if <code>spark</code> is being called with only a
string, the string will be assumed to be the SPARQL query and all other options
will be set to their default values).
				</p>
				<p>
The options object may include the following fields:
				</p>
				<ul>
					<li>
<code>endpoint</code>: The URL of the SPARQL endpoint to be queried.
Per default, the <a href="http://qcrumb.com">qcrumb.com</a> endpoint at
<code>http://qcrumb.com/sparql</code> will be used.
					</li>
					<li>
<code>format</code>: The URL (or name) of the formatter to be used. Per
default, <code>simple</code> will be used.
					</li>
					<li>
<code>format</code>: The URL (or name) of the formatter to be used. Per
default, <code>simple</code> will be used.
					</li>
					<li>
<code>rdf</code>: The URL of the RDF file to be queried. The default is blank.
					</li>
					<li id="ns">
<code>ns</code>: An object where the keys are the prefixes and the values are
the resolving namespaces. Per default the standard values for
<a href="http://prefix.cc/rdf">rdf</a>, <a href="http://prefix.cc/rdfs">rdfs</a>, <a href="http://prefix.cc/owl">owl</a>, <a href="http://prefix.cc/rif">rif</a>, <a href="http://prefix.cc/foaf">foaf</a>, <a href="http://prefix.cc/dbp">dbp</a>, <a href="http://prefix.cc/db">db</a>, <a href="http://prefix.cc/geo">geo</a>, and <a href="http://prefix.cc/dc">dc</a> are already given.
					</li>
					<li>
<code>param</code>: An object where the parameters for the formatter are given.
Per default, the object is empty. The parameters have the same name as for
the mark-up, and the documentation can be found in the given format
definition.
					</li>
				</ul>
				<p>
Whereas the mark up version is obviously preferable for more or less static
content, you can also use a dynamic browser with <strong>Spark</strong> via
the JavaScript interface.
				</p>
				<h2 id="formats">Spark query result formats</h2>
				<p>
<strong>Spark</strong> already ships with a small set of result formats.
				</p>
				<h3>simple</h3>
				<p>
The simple formatter returns a flat list of all results.
				</p>
				<h3>ul</h3>
				<p>
The ul formatter returns a list of all results as an unordered list, using
the HTML <code>&lt;ul&gt;</code> element.
				</p>
				<h3>count</h3>
				<p>
The count formatter returns merely the number of results.
				</p>
				<h3>http://km.aifb.kit.edu/sites/spark/src/jquery.spark.simpletable.js</h3>
				<p>
The simple table formatter returns a simple table, where each SPARQL variable
has a column. This is obviously too simple for real usages, but the formatter
provides both an example of how to write a format, and a rather verbose and
easy to understand rendering of the result set possibly useful for debugging.
				</p>
				<h2 id="newformats">Write your own Spark query result format</h2>
				<p>
You can easily extend the set of formats. The code documentation of the
<a href="../src/jquery.spark.simpletable.js">simpletable</a>
format provides a heavily documented example and adds further notes on how to
write your own formatter.
				</p>
				<h2 id="mediawiki">Spark in MediaWiki</h2>
				<p>
Planned: an extension of MediaWiki to include Spark. Will be linked from here.
				</p>
				<h2 id="drupal">Spark in Drupal</h2>
				<p>
Planned: an extension of Drupal to include Spark. Will be linked from here.
				</p>
				<h2 id="wordpress">Spark in WordPress</h2>
				<p>
Planned: an extension of WordPress to include Spark. Will be linked from here.
				</p>
				<h2 id="examples">Examples</h2>
				<p>
See <a href="example">example gallery</a>.
				</p>
				<h2 id="development">Spark development</h2>
				<p>
<strong>Spark</strong> is currently available as a pre-release version, i.e.
merely a developer peak. There are a number of open issues that need to be
resolved before we can go for a proper release:
				</p>
				<ol>
					<li>
Spark currently does not work with Internet Explorer and Opera due to Cross
Site Scripting security issues. Spark should run on all major browsers.
					</li>
					<li>
Spark currently assumes that the SPARQL endpoint is capable of returning
a JSON result set. It should also be able to deal with the more standard
XML result set.
					</li>
					<li>
Spark currently does not offer the possibility to easily define behavior
for error cases, like if the endpoint does not give a proper answer, or if
a certain URL can not be resolved, etc.
					</li>
					<li>
Spark currently features a tiny set of formats. Further formats can be written
and included in the standard release.
					</li>
				</ol>
				<p>
We would be very happy if more developers would join the further development of
<strong>Spark</strong>, especially with the above given tasks.
				</p>
				<p>
For more information, see the
<a href="http://code.google.com/p/rdf-spark/">Google code page</a>.
				</p>
				<h2 id="cite">How to acknowledge / cite Spark</h2>
				<p>
The main developers of <strong>Spark</strong> are researchers. We don't ask you
for money in order to use <strong>Spark</strong> (though if you like it, we
sure don't mind if you show us your appreciation in a monetary way), but
instead we would be very happy if you use it widely and acknowledge it.
				</p>
				<p>
One way to acknowledge us is to link to us. If you create little buttons that
can be used for that, please let us know so we can point to them and others
can use them too.
				</p>
				<p>
If you are writing a paper and want to cite <strong>Spark</strong>, you can
use the following citation (currently, it is merely a tech report, and yet
unpublished):
				</p>
				<p>
Denny Vrandecic, Andreas Harth: Visualising SPARQL result sets with Spark.
Tech Report. Karlsruhe, Institute AIFB, KIT, 2011.
				</p>
				<hr>
				<p>
					For questions feel free to mail
					<a href="mailto:denny.vrandecic@kit.edu">Denny</a>
					and
					<a href="mailto:harth@kit.edu">Andreas</a>.
				</p>
				<footer>
				  <p>
					<a href="../">[main page]</a>
					&mdash;
					<a href="../news.html">[news]</a>
					&mdash;
					[documentation]
					&mdash;
					<a href="example/">[examples]</a>
					&mdash;
					<a href="http://code.google.com/p/rdf-spark/">[development site]</a>
				</p>
				  <p>
					<a href="http://www.aifb.kit.edu"><img alt="KIT" border="0" title="KIT" src="kit.png" width="70" height="26" /></a>
					Developed 2011 by
					<a href="http://denny.vrandecic.de">Denny Vrande&#269;i&#263;</a>
					and
					<a href="http://harth.org/andreas/">Andreas Harth</a>
				  </p>
				</footer>
			</div>
		</div>
	</body>
</html>
